http-basic
Simple wrapper arround http.request/https.request
Installation
npm install http-basic
Usage
var request = require('http-basic');
var options = {followRedirects: true, gzip: true, cache: 'memory'};
var req = request('GET', 'http://example.com', options, function (err, res) {
if (err) throw err;
console.dir(res.statusCode);
res.body.resume();
});
req.end();
method:
The http method (e.g. GET
, POST
, PUT
, DELETE
etc.)
url:
The url as a string (e.g. http://example.com
). It must be fully qualified and either http or https.
options:
headers
- (default {}
) http headersagent
- (default: false
) controlls keep-alive (see http://nodejs.org/api/http.html#http_http_request_options_callback)followRedirects
- (default: false
) - if true, redirects are followed (note that this only affects the result in the callback)maxRedirects
- (default: Infinity
) - limit the number of redirects allowed.allowRedirectHeaders
(default: null
) - an array of headers allowed for redirects (none if null
).gzip
(default: false
) - automatically accept gzip and deflate encodings. This is kept completely transparent to the user.cache
- (default: null
) - 'memory'
or 'file'
to use the default built in caches or you can pass your own cache implementation.timeout
(default: false
) - times out if no response is returned within the given number of milliseconds.socketTimeout
(default: false
) - calls req.setTimeout
internally which causes the request to timeout if no new data is seen for the given number of milliseconds.retry
(default: false
) - retry GET requests. Set this to true
to retry when the request errors or returns a status code greater than or equal to 400 (can also be a function that takes (err, req, attemptNo) => shouldRetry
)retryDelay
(default: 200
) - the delay between retries (can also be set to a function that takes (err, res, attemptNo) => delay
)maxRetries
(default: 5
) - the number of times to retry before giving up.
callback:
The callback is called with err
as the first argument and res
as the second argument. res
is an http-response-object. It has the following properties:
statusCode
- a number representing the HTTP Status Codeheaders
- an object representing the HTTP headersbody
- a readable stream respresenting the request body.url
- the URL that was requested (in the case of redirects, this is the final url that was requested)
returns:
If the method is GET
, DELETE
or HEAD
, it returns undefined
.
Otherwise, it returns a writable stream for the body of the request.
Implementing a Cache
A Cache
is an object with two methods:
getResponse(url, callback)
- retrieve a cached response objectsetResponse(url, response)
- cache a response object
A cached response object is an object with the following properties:
statusCode
- Numberheaders
- Object (key value pairs of strings)body
- Stream (a stream of binary data)requestHeaders
- Object (key value pairs of strings)requestTimestamp
- Number
getResponse
should call the callback with an optional error and either null
or a cached response object, depending on whether the url can be found in the cache. Only GET
s are cached.
setResponse
should just swallow any errors it has (or resport them using console.warn
).
A cache may also define any of the methods from lib/cache-utils.js
to override behaviour for what gets cached. It is currently still only possible to cache "get" requests, although this could be changed.
License
MIT